home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / docs / apps / database / ingres04.lzh / doc / quel / copy.doc < prev    next >
Encoding:
Text File  |  1992-11-19  |  8.5 KB  |  185 lines
  1.  
  2.  
  3.  
  4.  
  5.      COPY(QUEL)                   1/19/79                   COPY(QUEL)
  6.  
  7.  
  8.  
  9.      NAME
  10.           copy - copy data into/from a relation from/into a UNIX file.
  11.  
  12.      SYNOPSIS
  13.           _c_o_p_y relname (domname = format {, domname = format })
  14.                     direction "filename"
  15.  
  16.      DESCRIPTION
  17.           _C_o_p_y moves data between INGRES relations and  standard  UNIX
  18.           files.   _R_e_l_n_a_m_e  is  the  name of an existing relation.  In
  19.           general _d_o_m_n_a_m_e identifies a domain in _r_e_l_n_a_m_e.  _F_o_r_m_a_t  in-
  20.           dicates  the  format  the  UNIX  file  should  have  for the
  21.           corresponding domain.  _D_i_r_e_c_t_i_o_n is  either  _i_n_t_o  or  _f_r_o_m.
  22.           _F_i_l_e_n_a_m_e is the full UNIX pathname of the file.
  23.  
  24.           On a copy _f_r_o_m a file to a  relation,  the  relation  cannot
  25.           have a secondary index, it must be owned by you, and it must
  26.           be updatable (not a secondary index or system relation).
  27.  
  28.           _C_o_p_y cannot be used on a relation which is a  view.   For  a
  29.           copy  _i_n_t_o  a UNIX file, you must either be the owner of the
  30.           relation or the relation must have retrieve  permission  for
  31.           all users, or all permissions for all users.
  32.  
  33.           The formats allowed by copy are:
  34.  
  35.           _i_1,_i_2,_i_4 - The data is stored as an integer of length 1,  2,
  36.                or 4 bytes in the UNIX file.
  37.  
  38.           _f_4,_f_8 - The data is stored as a floating point  number  (ei-
  39.                ther single or double precision) in the UNIX file.
  40.  
  41.           _c_1,_c_2,...,_c_2_5_5 - The data is stored as a fixed length string
  42.                of characters.
  43.  
  44.           _c_0 - Variable length character string.
  45.  
  46.           _d_0,_d_1,...,_d_2_5_5 - Dummy domain.
  47.  
  48.           Corresponding domains in the relation and the UNIX  file  do
  49.           not  have  to be the same type or length.  _C_o_p_y will convert
  50.           as necessary.  When converting anything except character  to
  51.           character,  _c_o_p_y  checks for overflow.  When converting from
  52.           character to character, _c_o_p_y will blank pad or  truncate  on
  53.           the right as necessary.
  54.  
  55.           The domains should be ordered  according  to  the  way  they
  56.           should appear in the UNIX file.  Domains are matched accord-
  57.           ing to name, thus the order of the domains in  the  relation
  58.           and in the UNIX file does not have to be the same.
  59.  
  60.           _C_o_p_y also provides for variable  length  strings  and  dummy
  61.           domains.   The  action taken depends on whether it is a copy
  62.           _i_n_t_o or a copy _f_r_o_m.  Delimitors for variable length strings
  63.           and for dummy domains can be selected from the list of:
  64.  
  65.               _n_l - new line character
  66.               _t_a_b - tab character
  67.               _s_p - space
  68.               _n_u_l or _n_u_l_l - null character
  69.               _c_o_m_m_a - comma
  70.               _c_o_l_o_n - colon
  71.               _d_a_s_h - dash
  72.               _l_p_a_r_e_n - left parenthesis
  73.               _r_p_a_r_e_n - right parenthesis
  74.               _x - any single character 'x'
  75.  
  76.           The special meaning of any delimitor can be  turned  off  by
  77.           preceeding the delimitor with a `\'.  The type specifier can
  78.           optionally be in quotes ("c0delim").  This  is  usefully  if
  79.           you  wish to use a single character delimitor which has spe-
  80.           cial meaning to the QUEL parser.
  81.  
  82.           When the _d_i_r_e_c_t_i_o_n is from, _c_o_p_y appends data into the rela-
  83.           tion  _f_r_o_m  the  UNIX  file.  Domains in the INGRES relation
  84.           which are not assigned values from the  UNIX  file  are  as-
  85.           signed  the  default  value of zero for numeric domains, and
  86.           blank for character domains.  When copying in this direction
  87.           the following special meanings apply:
  88.  
  89.           _c_0_d_e_l_i_m - The data in the UNIX file  is  a  variable  length
  90.                character string terminated by the delimitor _d_e_l_i_m.  If
  91.                _d_e_l_i_m is missing then the first comma, tab, or  newline
  92.                encountered  will  terminate the string.  The delimitor
  93.                is not copied.
  94.  
  95.                For example:
  96.                     pnum=c0 - string ending in comma, tab, or nl.
  97.                     pnum=c0nl - string ending in nl.
  98.                     pnum=c0sp - string ending in space.
  99.                     pnum=c0z - string ending in the character `z'.
  100.                     pnum="c0%" - string ending in the character `%'.
  101.  
  102.                A delimitor can be escaped by preceeding it with a `\'.
  103.                For  example,  using  _n_a_m_e  =  _c_0,  the string ``Blow\,
  104.                Joe,'' will be accepted  into  the  domain  as  ``Blow,
  105.                Joe''.
  106.  
  107.           _d_0_d_e_l_i_m - The data in the UNIX file  is  a  variable  length
  108.                character  string  delimited  by  _d_e_l_i_m.  The string is
  109.                read and discarded.  The delimitor rules are  identical
  110.                for _c_0 and _d_0.  The domain name is ignored.
  111.  
  112.           _d_1,_d_2,...,_d_2_5_5 - The data in the UNIX file is a fixed length
  113.                character  string.   The  string is read and discarded.
  114.                The domain name is ignored.
  115.  
  116.           When the direction is _i_n_t_o, _c_o_p_y  transfers  data  _i_n_t_o  the
  117.           UNIX  file  from the relation.  If the file already existed,
  118.           it is truncated to zero length before copying begins.   When
  119.           copying  in  this  direction, the following special meanings
  120.           apply:
  121.  
  122.           _c_0 - The domain value is converted to a fixed length charac-
  123.                ter string and writted into the UNIX file.  For charac-
  124.                ter domains, the length will be the same as the  domain
  125.                length.   For  numeric  domains,  the  standard  INGRES
  126.                conversions will take place as specified by  the  `-_i',
  127.                `-_f', and `-_c' flags (see ingres(unix)).
  128.  
  129.           _c_0_d_e_l_i_m - The domain will  be  converted  according  to  the
  130.                rules  for  _c_0 above.  The one character delimitor will
  131.                be inserted immediately after the domain.
  132.  
  133.           _d_1,_d_2,...,_d_2_5_5 - The domain name is taken to be the name  of
  134.                the delimitor.  It is written into the UNIX file 1 time
  135.                for _d_1, 2 times for _d_2, etc.
  136.  
  137.           _d_0 - This format is ignored on a copy _i_n_t_o.
  138.  
  139.           _d_0_d_e_l_i_m - The _d_e_l_i_m is written into the  file.   The  domain
  140.                name is ignored.
  141.  
  142.  
  143.           If no domains appear in the copy command (i.e. copy  relname
  144.           ()  into/from  "filename")  then  _c_o_p_y  automatically does a
  145.           ``bulk'' copy of all domains, using the order and format  of
  146.           the  domains  in  the  relation.  This is provided as a con-
  147.           venient shorthand notation for copying and restoring  entire
  148.           relations.
  149.  
  150.           To _c_o_p_y into a relation, you must be the owner or all  users
  151.           must  have  all  permissions  set.  Correspondingly, to _c_o_p_y
  152.           from a relation you must own the relation or all users  must
  153.           have  at  least  retrieve permission on the relation.  Also,
  154.           you may not _c_o_p_y a view.
  155.  
  156.      EXAMPLE
  157.           /* Copy data into the emp relation */
  158.              copy emp (name=c10,sal=f4,bdate=i2,mgr=c10,xxx=d1)
  159.                         from "/mnt/me/myfile"
  160.  
  161.           /* Copy employee names and their salaries into a file */
  162.              copy emp (name=c0,comma=d1,sal=c0,nl=d1)
  163.                           into "/mnt/you/yourfile"
  164.  
  165.           /* Bulk copy employee relation into file */
  166.              copy emp ()
  167.                           into "/mnt/ours/ourfile"
  168.  
  169.           /* Bulk copy employee relation from file */
  170.              copy emp ()
  171.                           from "/mnt/thy/thyfile"
  172.  
  173.      SEE ALSO
  174.           append(quel),   create(quel),   quel(quel),    permit(quel),
  175.           view(quel), ingres(unix)
  176.  
  177.      BUGS
  178.           _C_o_p_y stops operation at the first error.
  179.  
  180.           When specifying _f_i_l_e_n_a_m_e, the entire UNIX directory pathname
  181.           must  be  provided, since INGRES operates out of a different
  182.           directory than the user's  working  directory  at  the  time
  183.           INGRES is invoked.
  184.  
  185.